블로그_01_블로그 웹 구축 계획

• 학습한 내용을 정리하고 아카이빙하는 Knowledge Base 웹사이트 구축하기
• 일반 블로그나 Tistory 등을 사용해도 되겠으나, 내가 원하는 대로 커스텀하고 싶었기 때문

웹사이트 구조

메인 페이지

• Hero 섹션
  • 간단한 제목 및 소개 문구
  • 주요 기술 스택 배지 표시 (Next.js 14, TypeScript, Tailwind CSS, Zustand)
  • 네비게이션 버튼 컴포넌트
    • 노트 보기: /notes로 이동
    • 블로그 보기: /journal로 이동
    • 태그로 보기: /tags로 이동 (태그 개수 표시)
• 요약 섹션
  • 전체 노트 (StatsCard)
    • 전체 노트 개수 표시
    • 최근 업로드된 노트 리스트: 최신순 3개를 보여주며, 클릭 시 해당 문서로 바로 이동 (불필요한 서브텍스트 제거 및 줄간격 최적화)
  • 최근 활동 (ContributionGraph)
    • 최근 63일(약 2달) 간의 활동량을 GitHub 잔디(Heatmap) 스타일로 시각화
    • 자동 카테고리 감지: 가장 최근에 활동이 있었던 폴더(카테고리)를 자동으로 제목에 표시
    • 상세 정보 표시: 그래프 하단에 가장 최근 작성/수정된 게시물의 제목과 날짜를 표시 (같은 날짜일 경우 파일 수정 시간(mtime) 기준 최신 파일 우선)
• 링크 섹션
  • 공부하면서 개발한 프로젝트들을 카드 형태로 전시
  • 현재 0room, rootcamp 연결 완료

노트 페이지 (/notes/[...slug])

• 계층형 구조: 폴더 구조를 그대로 URL(slug)에 반영하여 체계적인 정리 가능
• MDX 지원: 마크다운 문법 외에 React 컴포넌트 사용 가능 (현재는 표준 Markdown 위주 사용)
• 헤더 정보:
  • Breadcrumb 스타일의 상위 폴더명 표시 (한글 경로 디코딩 적용 완료)
  • 제목, 작성자(Heehyeon Yoo), 작성일, 태그 목록 표시
• 백링크(Backlinks): 해당 문서를 참조하는 다른 문서들의 링크를 하단에 자동 생성

블로그 페이지 (/journal/[...slug])

• 노트와 유사한 구조를 가지되, 개발 일지 및 생각 정리를 위한 공간으로 분리
• 헤더에 'Dev Log' 대신 해당 폴더명(예: 웹사이트 작업)을 디코딩하여 표시하도록 개선

태그 페이지 (/tags)

• 태그 클라우드: 전체 게시물에서 수집된 태그 목록과 각 태그별 포스트 개수 표시
• 필터링: 특정 태그 클릭 시 해당 태그가 포함된 게시물 목록(Title, Link) 제공
• 동적 링크: 게시물 클릭 시 강제로 /notes가 붙지 않고, 실제 경로(/journal 등)에 맞게 이동하도록 라우팅 처리

주요 기능

파일 시스템 기반 게시물 관리 (MD, MDX)

• fs 모듈과 path 모듈을 사용하여 content 디렉토리 내의 모든 파일을 재귀적으로 탐색
• gray-matter 라이브러리를 이용해 Frontmatter(YAML 메타데이터)와 본문 파싱
• 한글 경로 지원: URL 인코딩된 경로(%EC...)를 decodeURIComponent로 처리하여 파일 시스템에서 정확하게 파일을 찾도록 구현

검색 기능 (SearchModal)

• 실시간 검색: 제목 및 태그를 기준으로 즉시 필터링
• 접근성: 헤더의 검색 버튼 또는 키보드 단축키로 접근 가능
• 정확한 라우팅: 검색 결과 클릭 시 해당 문서의 정확한 경로(Slug 기반)로 이동 (하드코딩된 접두사 제거)

백링크 (Backlinks)

• 모든 포스트를 스캔하여 현재 문서의 경로를 포함하고 있는 문서를 역추적
• 양방향 지식 연결 구조 형성

태그 기능

• getAllTags 유틸리티를 통해 중복 없는 태그 목록 및 카운트 생성
• 게시물 상단 및 검색 결과에 태그 노출로 탐색 용이성 증대

기술적 해결 과제 (Troubleshooting)

• 우선순위 로직: 같은 날짜에 여러 글이 올라올 경우, fs.stat의 mtime(수정 시간)을 비교하여 가장 최신 글을 정확히 선별
• 한글 인코딩: 브라우저 URL의 한글이 인코딩되어 파일 시스템 매칭이 실패하는 문제를 decodeURIComponent 도입으로 해결
• UI 최적화: ContributionGraph의 높이를 3줄로 줄여 StatsCard와 높이 균형을 맞추고, 정보를 밀도 있게 배치
• 디자인 개선:
  • Notion 벤치마킹: 본문 폭을 max-w-3xl로 좁히고 글자 크기를 prose-sm으로 줄여 가독성 향상
  • 코드 블록 스타일링: 인라인 코드에는 빨간 텍스트/회색 배경을 적용하고, 코드 블록에는 rehype-highlight를 통한 Syntax Highlighting 적용 (GitHub Dark 테마)
• 편의 기능 추가:
  • 글자 크기 토글: 상세 페이지 우측 상단에 'T' 버튼 구현. zustand와 로컬 스토리지를 사용하여 사용자 설정(기본/작게) 저장 및 유지
• 빌드 오류 해결:
  • highlight.js의 CSS import 경로 문제로 인한 빌드 실패를 패키지 명시적 설치 및 layout.tsx로의 import 이동으로 해결
• 스마트 링크 시스템:
  • MDX 내부 링크에서 .md 확장자를 자동으로 제거하고, 한글 경로를 안전하게 처리하는 CustomLink 컴포넌트 도입.
  • 사용 팁: 파일명에 띄어쓰기가 있는 경우, [텍스트](</경로/파일명>) 처럼 주소를 < >로 감싸주면 인코딩 없이도 IDE와 웹사이트 모두에서 링크가 정상 작동함.